Oreo Triggers (Topic)

Oreo triggers is an SCMDraft trigger preprocessor that runs on php. More than a macro-triggerer, it adds modularity, intuitive triggering, EUD and Deathcounter support, helps you manage your resources and allows for custom built actions and conditions.

( It doesn't let you do anything you couldn't already do in Scmdraft, it just helps you do it more easily. )

Note about php:
If I had started with what this project ended up being in mind (and if I had planned to release it to people) I wouldn't've used php. As it happens, I originally started this as a simple preprocessor for Wormer's Macrotriggers (to add another layer of abstraction), which, at that level php was a natural choice. As it stands, however, php is great for people just being introduced to programming as it is a loosely typed language. To use Oreo triggers, you'll have to familiarize yourself with the php syntax (or at least, how it's used in Oreo triggers).

Just so you have a better idea of what this is before I go on, here's an example of what triggers might look like using Oreo triggers:

Example

	$P1 = new Player("Player 1");
	$spawntimer = new Deathcounter();

	$P1->_if( $spawntimer->exactly(0) )->then(
		Display('Spawn timer set to 10 seconds'),
		$spawntimer->setTo(120),
	'');

	$P1->always(
		$spawntimer->subtract(1),
	'');

Its Result

Trigger("Player 1") {
Conditions:
	Deaths("Player 1", "Duke Turret type 2", Exactly, 0);
Actions:
	Preserve Trigger();
	Comment("");
	Display Text Message(Always Display, "Spawn timer set to 10 seconds");
	Set Deaths("Player 1", "Duke Turret type 2", Set To, 120);
}

//-----------------------------------------------------------------//

Trigger("Player 1") {
Conditions:
	Always();
Actions:
	Preserve Trigger();
	Comment("");
	Set Deaths("Player 1", "Duke Turret type 2", Subtract, 1);
}

//-----------------------------------------------------------------//

Installation and Usage
1. Install/Setup Oreos package

Install a local php server (I use Zend Server CE)
Download the Oreos Package (link below)
Unzip and place the Oreos folder in either your htdocs (windows) or public_html (linux) server folder (for Zend Server CE on Windows it should be ProgramFiles/Zend/Apache2/htdocs)

2. Create a your Oreo trigger projects in the same directory as the Oreos folder (but not in the Oreos folder).

Oreo projects are just php files that have:
<?php require_once('Oreos/initialize.php');
at the beginning and:
?>
at the end. The actual oreo code you write will be in-between. You can edit .php files with any text editor, although it is best to use a programming environment that supports php.

3. Actually write your oreo triggers (using the oreo functions and classes. How to do this is explained in sections below).
4. Visit your project in a web browser to generate the triggers

Visiting your php file in a browser causes the php script to execute (and thus generate your map's triggers).
If you created your project in your web root (public_html or htdocs folder) then the url to visit the project will be:
localhost/projectname.php

5. Copy and paste the generated triggers into the SCMDraft Textual Trig Editor

Using Mint
After some collaboration with yoonkwun (thanks yoonkwun), we developed an extension called 'Mint', which lets you write triggers to your map merely by compiling. With Mint enabled, you no longer have to copy/paste the generated text into Scmdraft, the triggers are added for you. This also gives you the ability to generate units and locations to your map within Oreo trigs. (Mint is not a separate download, its included in the Oreos package, and is completely optional).
To use mint, you must provide a path to your input file and an output file path to the Mint() function. Ex:

Mint takes your input map file and adds the triggers Oreo generates to it. Your input map should not have the triggers in it. There are few reasons we do it this way instead of overwriting the triggers onto the original file- it protects your map from the off chance that it gets corrupted, it keeps the triggers units and locations (made by OT) from being added to your map multiple times, and it makes it so that you don't have to reload the map in Scmdraft after compiling.
Your typical work flow would go like this- keep the original/input map open in Scmdraft (for making physical changes to the map, like terran, units, sprites) and oreo triggers in whatever IDE your using (for making changes to the triggers). Whenever you make a change to the map in either Scmdraft or in Oreo Trigs, you recompile OT and the changes will appear in the output map. When you test in Starcraft, you test with your output map file (where all the physical map and triggers are combined).

To create a preplaced unit or location to the map using Mint Oreos, simply use these functions:

	$Players = new Player("Player 1", "Player 2", "Player 3");

Any trigger created with the player object you define will be owned by the players you specified when you created it.

There are 4 ways to start a trigger:

$Players->always( actions )

The actions you put in the always parameters will be carried out every loop.

	$Players->always(
		Display('SPAMMING YOUR SCREEN WITH TEXT!'),
	'');

$Players->justonce( actions )

The actions you put in the justonce parameters will be carried out just once (during the first trigger loop of the game).

	$Players->justonce(
		SetAlly($Players),
	'');

$Players->never( actions )

$Players->_if( conditions )->then( actions )

Allows you to specify the conditions that must be satisfied in order for the actions to be executed. This is the bread and butter of your triggering. All "_if()" triggers must have a "->then()" attached to them. You specify the conditions in the "_if()" parameters, and the actions in the "then()" parameters.

	// After 7 seconds into the game, P1, P2, P3 get 1 ore each loop
	$Players->_if( Elapsed(AtLeast, 7) )->then(
		$Players->addOre(1),
	'');

Conditions should be comma separated.
You can also use "then_justonce()" instead of then() to execute the actions only once (essentially, stops it from adding preserve trigger)

	$Players->_if( Elapsed(AtLeast,10) )->then_justonce(
		Display('10 seconds have elapsed!'),
	'');

If you want something to occur if the conditions aren't met then you can use "_else()" and "_elseif()->then()". Note that if you use an _else or _ifelse you must pass "e", into the action set before it as shown:

EX1:

	$Players->always(
		ClearText(), 	// custom oreo action that just displays 11 blank lines
	'')

	$Players->_if( $myswitch->is_set() )->then(
		Display('My Switch is set!'),
	e)->_else(
		Display('My Switch is clear!'),
	'');

EX2:

	$Players->_if( conditions )->then(
		actions,
	e)->_elseif( conditions )->then(
		actions,
	e)->_elseif( conditions )->then(
		actions,
	e)->_else(
		actions,
	'');

You can also nest _ifs

	$Players->_if( conditions )->then(
		actions,
		_if( conditions )->then(
			actions,
		''),
		actions,
	'');

If you have a nested _if, then you don't prepend the player object (That is, don't put $player-> before nested _ifs).
Combining these concepts allows for some complex logic.

	$Players->_if( conditions )->then(
		actions,
		_if( conditions )->then(
			actions,
			_if( conditions ) ->then(
				actions,
			e)->_else(
				actions,
			''),
			actions,
		e)->_elseif( conditions )->
			actions,
		e)->_elseif( conditions )->
			actions,
			_if( conditions )->then(
				actions,
				_if( conditions )->then(
					actions
				''),
				actions,
			e)->_else(
				actions,
			''),
		''),
		actions,
	e)->else(
		actions,
	'');

Not that you should ever need to do something like that.

Version History

09/05/13 Lots of changes, see post notes (1.0.1)
11/08/12 Deathcounters can be used in Display Text. ->enter and ->exit for UnitGroups. Update checking (0.9.6)
09/24/12 Fixes mint bug with Dark Swarm Nuclear Missile becoming the wrong units, fixes bug with complex conditions and more (0.9.5)
08/23/12 A lot of changes, see notes (0.9.4)
07/12/12 Added Leaderboard functions, fixed centerview for mint, added ModifyHangar, and more bug fixes (0.9.3)
07/07/12 Added ForemostPlayer() function, Event and PlayerSwitch classes, fixed deathcounter division functions and other bug fixes. (0.9.2)
06/30/12 Added repeat() and MintMapRevealers() functions. Fixed a bug where it wasn't removing extraneous triggers, and a bug when using the Order action with Mint. (0.9.1)
06/26/12 Added support for all vanilla Conditions. Mint Extension released. Some bug fixes, a few more functions. LeaderBoard condition renamed to LeaderBoardPoints. (0.9.0)
06/17/12 Added Switch statements, and more UnitGroup, IndexedUnit and Deathcounter functions as well as some minor bugfixes (0.8.5)
06/08/12 Fixed create unit properties bug (0.8.4)
06/08/12 Player objects in conditions support, Create unit with properties support, orGroups (0.8.3)
06/07/12 Minor bug fix, Player in actions support, Comments moved to end of trigger (0.8.2)
06/02/12 Fixed a bug in deathcounter multiply functions (0.8.1)
06/02/12 Oreo Triggers Released (0.8)

Other Remarks
There are more classes I haven't touched and much more to tell, but it's late I'm tired of writing and I'm eager to release. Special thanks to Lethal Illusion for volunteering to do the Deathcounter math functions, the EUD classes and helping me test. More thanks: Roy, Yoonkwun, Farty1Billion for EUD work, Wormer for Macrotriggers documentation, and R1SKED911 for ever existing.

Remember, it's still in beta stage. Feel free to rifle through the code and change things to your liking (I recommend putting any additions you might make to a separate document and then just including them onto the proper page). Also feel free to contribute and make this thing even better.

Post has been edited 21 time(s), last time on Sep 6 2013, 2:02 am by Kaias.

None.

Documentation

CONDITIONS

ACTIONS

Deathcounters

Oreo triggers provides inherent support for using deathcounters like (limited) SC variables. Declaring a new deathcounter in the preprocessor is done like so:

	$dc = new Deathcounter(Max);

When a new deathcounter is declared Oreo trigs automatically allocates a unit/player combination for it for future use.
If the above deathcounter object $dc happens to be allocated the unit/player combination of Player 3 Terran Beacon, then the oreo action:

	$dc->setTo(10)

Will generate the scmdraft trigger code:

	Set Deaths("Player 3", "Terran Beacon", Set To, 10);

Setting the Deathcounter's Max lets the system know how large it can expect the deathcounter to get. This is for efficiency- if you set the Max to 500 then the compiler will only produce binary count offs high enough to reach 500 (256). If you set the Max to 100 and the value manages to exceed that ingame, then there is a high chance that functions using binary count off will mess up. It is therefore important that you set a high enough Max.
If you don't set a Max value, it will default to 2147483647. It is highly recommended that you set the Max value as having a max of 2147483647 will result in highly inefficient Deathcount triggers.

If you pass in "Current Player", "Allies", "All players", or "Foes" on declaration the preprocessor will allocate an entire unit (all of its players) to the Deathcounter.

	$timerdc = new Deathcounter(CP, 500); // A new deathcounter is declared for Current Player (CP is a constant for "Current Player"), with a max of 500

When you utilize the object it will default to the player you declared it with. For example:

	$timerdc->atLeast(10)

Will generate the scmdraft condition:

	Deaths("Current Player", "Goliath Turret", At least, 10);

if $timerdc happens to be allocated the "Goliath Turret" unit.
You can cast for a specific player like so:

	$timerdc->P1->atLeast(10)

which will generate:

	Deaths("Player 1", "Goliath Turret", At least, 10);

Available castings:
->P1, ->P2, ->P3, ->P4, ->P5, ->P6, ->P7, ->P8, ->CP, ->AllPlayers, ->Allies, ->Foes

Practical application:

	$humans = new Player(P1,P2,P3,P4);
	$spawntimer = new Deathcounter(CP,200);
	
	$humans->_if( Command(CurrentPlayer,'Terran Marine', Exactly, 0) )->then(
		$spawntimer->setTo(60),
	'');
	
	$humans->_if( $spawntimer->exactly(1) )->then(
		CreateUnit(CP,'Terran Marine', 1, '_TownLocation'),
	'');

	$humans->always(
		$spawntimer->subtract(1),
	'');

The above code will make it so that whenever Player 1, 2, 3, or 4 lose their Marine a new one will be created for them at location '_TownLocation' after 5 seconds. Because $spawntimer was created for CP (current player), it uses current player.

Oreo deathcounter functions:

More in-depth documentation here: https://docs.google.com/document/d/1-EVk96_9RWDdU-gj5LOmsNlfjhBWSLSdoqBa8NkZauc/edit

Switches

Like deathcounters, creating a switch object automatically allocates a switch to it. There are two types of switch objects- PermSwitch, and TempSwitch.

	$HasVisitedTown = new PermSwitch();
	$nestswitch = new TempSwitch();

PermSwitches are for switches that could potentially be used or set through multiple player's triggers and could be set for more than one loop. TempSwitches, however, are intended only for use within a single system, and should always be cleared (and released) at the end of the trigger system they're used in. For beginners, you should pretty much always use PermSwitches (because they're intended for use in ways that are familiar).

The difference between the types of switches is this: TempSwitches can be allocated switches that have been used previously by other TempSwitches (and must be) released when you're done using them (using the ->kill() method). PermSwitches cannot be released (un-allocated) and will never be allocated a switch slot that has been used previously (by released TempSwitches).

PermSwitch Example:

	$HasVisitedTown = new PermSwitch();
	$P1->_if( $HasVisitedTown->is_cleared, Bring(P1, 'Terran Ghost', AtLeast, 1, '_TownLocation') )->then(
		$HasVisitedTown->set(),
		Display('Welcome to Kurast, stranger! Come visit the blacksmith!'),
	'');

Switch Functions:

// CONDITIONS

->is_set()
->is_clear()

// ACTIONS

->set()
->clear()
->toggle()
->randomize()

->kill() // TempDC only
->killTrigger() //TempDC only

KeyStroke

Provides support for local EPD keyboard detection (For Windows SC 1.16.1)

Creating a KeyStroke object automatically creates triggers (owned by the last player group to own a trigger)
that give you access to the pressed, released, isUp and isDown conditions for the key group passed into the constructor.
When chat is open it automatically stops detecting the keys being pressed (with the exception of left click detection).
 
Ex1:
	$QKey = new KeyStroke(Q);
	$Player->_if( $QKey->pressed() )->then(
		Display('Q key was just pressed!'),
	'');
 
If multiple keys are passed into the KeyStroke on construction then the events will correspond to when all the keys
are down or up.

Ex2:
	$PlusKey = new KeyStroke(Shift,=);
	$Player->_if( $PlusKey->pressed() )->then(
		Display(' "Shift" and "=" were just pressed creating a "+" !'),
	'');'

Warning: 
	Certain combinations of keys won't work together (Shift, Ctrl or Alt with 0-9 for instance),
	simply because these have reserved meanings for Starcraft.

Resource Cost:
	Triggers: At most ( 5 + 11*[NumberOfKeysPassed] )
	Deathcounters: 1
	TempSwitches: 1 + [NumberOfKeysPassed]

Keystroke functions:

// CONDITIONS

->isDown()
->isUp()
->pressed()
->released()

UnitGroup

I'll probably continue writing the documentation tomorrow. I haven't even touched on the EPD, IndexedUnit, or Location classes.

Post has been edited 6 time(s), last time on Jun 16 2012, 11:02 pm by Kaias.

None.

>be faceless void >mfw I have no face

Very nice, I'll have to try this out and see if I can get the hang of it in time for the 1 week contest.

Red classic.

"In short, their absurdities are so extreme that it is painful even to quote them."

Still Napping

High five!

None.

It's intended for making all of your map's the triggers with, not just generating a few triggers and pasting it into your project (though you could certainly do that). Ideally you'll never have to open the Classic Trigger Editor.

This should be useful even in making little dinky maps.

None.

>be faceless void >mfw I have no face

With the deathcounters, does it automatically assign DCs? It seems so from your example code, but that would presumably interfere with any pre-selected DCs you might have in an existing map if you were copying and pasting just one trigger system, for example.

Red classic.

"In short, their absurdities are so extreme that it is painful even to quote them."

Quote from

Jack

With the deathcounters, does it automatically assign DCs? It seems so from your example code, but that would presumably interfere with any pre-selected DCs you might have in an existing map if you were copying and pasting just one trigger system, for example.

Yeah, it automatically assigns DCs, but you can tell the compiler which DCs are available and which aren't. Same goes for switches.

None.

>be faceless void >mfw I have no face

What is the empty value at the end of each trigger?

Code

'');

EDIT
On your tutorial, you may want to add that you need to be running the server executable to be able to run the .php script. And that you need to hit the Compile button in SCMDraft. Most people will work that out anyway but it's worth noting.

Red classic.

"In short, their absurdities are so extreme that it is painful even to quote them."

Quote from

Jack

What is the empty value at the end of each trigger?

Code

'');

That's just a blank parameter I put at the end of triggers so that all of my actions can end in a comma. It isn't at all necessary.

None.

Code

<?php require_once("Oreo/initialize.php");

$P1 = new Player("Player 1");
$spawntimer = new Deathcounter();

$P1->_if( $spawntimer->exactly(0) )->then(
Display('Spawn timer set to 10 seconds'),
$spawntimer->setTo(120),
'');

$P1->always(
$spawntimer->subtract(1),
'');

?>

Why doesn't this compile? I tried other files in the same directory as this and they work fine.

None.

If you're using 'require_once("Oreo/initialize.php");' to initialize the oreos package then your project file needs to be in the same directory as the Oreo folder (but not in the Oreo folder). If you want to put your projects in a different folder you'll need to change the path to find it properly.

"Oreo/initialize.php" is a relative path. You can make an absolute path like this:
require_once($_SERVER['DOCUMENT_ROOT']."/Oreo/initialize.php");
which would point to htdocs/Oreo/initialize.php. You'd then be able to put your project anywhere in htdocs.

None.

At first it didn't work so I tried changing it to require_once($_SERVER['DOCUMENT_ROOT']."/oreotriggers/Oreo/initialize.php"); and it worked fine.

None.

New Update 0.8.2:

You can now pass Player objects into actions and it will create the action for each player in the Player object
Autocomments moved to end of action list (so manual ones take priority)
Bugfix for deathcounter quotientOf and roundedQuotientOf functions
Added create() function to UnitGroup class
For efficient deathcounter allocation, you can now create Deathcounters for specific player slots by passing in a Player object on declaration. EX:
```
$players = new Player(P2, P3);
$dc = new Deathcounter($players, 500); // Creates a deathcounter with slots for P2 and P3 only reserved with a max of 500
```
Using the deathcounter will use a player name of "Current Player", so its your responsibility to use $dc only in triggers owned by the players you set it for (in this case Player 2 and 3). That or you can player cast (e.g. $dc->P3->setTo(0) to set the deathcounter for player 3 to 0 )

Download Link:
http://www.mediafire.com/?e8do8gta41kud7e

Next:
After gathering some opinions I'm going to make it so using Player objects in conditions treats it as though it were a force. For instance:
Bring( $players, 'Terran Marine', AtLeast, 1, 'Anywhere' )
(Where $players is a player object) will act like this: "If any of the players in $players bring at least 1 Marine to Anywhere then..." as opposed to "If all of the players in $players bring at least 1 Marine to Anywhere then..."

Post has been edited 1 time(s), last time on Jun 8 2012, 2:21 am by Kaias.

None.

Let me show you how to hump without making love.

Handy.

None.

New Update ~~0.8.3~~ 0.8.4:

You can now pass Player objects into conditions. By default it will act like a force would, where if any of the players meet the condition the actions are executed. EX:
```
$humans = new Player(P1, P2, P3);
Bring($humans, 'Terran Marine', AtLeast, 1, 'Anywhere')
```
Will have a result to the effect of "Player 1, 2, or 3 bring at least 1 Marine to Anywhere". Using $humans->any or $humans->or in place of $humans will have the same effect. If you use $humans->all, $humans->each or $humans->and it will require all the players to meet the condition. EX:
```
$humans = new Player(P1, P2, P3);
Bring($humans->each, 'Terran Marine', AtLeast, 1, 'Anywhere')
```
Will have a result to the effect of "Player 1, 2, AND 3 bring at least 1 Marine to Anywhere".

Create Unit with Properties now works. To use it, create an array of the property settings you want like so (order doesn't matter):

$properties = array(Invincible, LiftedOff, Cloaked, Hallucinated, Burrowed, Shields => 99, Health => 90, Resources => 500, Hangar => 10, Energy => 30);
CreateUnitWithProperties(P1, 'Terran Marine', 1, 'SpawnLocation', $properties)

If you pass in only a single flag instead of an array it will work as you'd expect. Example:

CreateUnitWithProperties(P1, 'Zerg Hydralisk', 1, 'SpawnLocation', Burrowed)

Which will create a burrowed hydralisk at 'SpawnLocation' for Player 1

Added function orGroup(). Any conditions you pass into it will be "Or'd". Example:

$Player->_if( $switch1->is_set(), orGroup( $QKey->pressed(), $EKey->pressed() ) )->then(
	Display('Q or E was pressed!')
);

In common programming syntax the conditions would translate to:

if( $switch1->is_set() && ( $QKey->pressed() || $EKey->pressed() ) ) then..

Moved generated triggers into a scrollable

Download Link:
http://www.mediafire.com/?6w1uk4idger78ex

Post has been edited 1 time(s), last time on Jun 9 2012, 7:27 am by Kaias.

None.

I'd just like to say its taken me a while to get into the syntax of Oreo, but its definitely more fun and intuitive once you get used to it.

None.

@Jack
It's a capitalization issue

Change
location('_p1Range');
to be
Location('_p1Range');

It seems that my version of PHP is less picky than yours (it didn't mind the capitalization issue).

By the way, I use PhpStorm as an IDE. I didn't like it at first because of how certain things worked and how ugly it was, but it is extremely configurable so I've been able to fix all my reservations (including the ugliness) and its better for Php than anything else I've used.

None.

>be faceless void >mfw I have no face

Excellent, that worked. Thanks for your help!

I'm using Notepad++ at the moment, it's nice and minimalist, and quick to load.

Red classic.

"In short, their absurdities are so extreme that it is painful even to quote them."

Quote from

Jack

Excellent, that worked. Thanks for your help!

I'm using Notepad++ at the moment, it's nice and minimalist, and quick to load.

I prefer PhpStorm primarily because it has good code hinting and error detection. So when you forget a comma or a parenthesis you know right away and when you want to use the Bring function it tells you exactly what its expecting. Using Notepad++ is indeed a great minimalist environment, however.

By the way, a location name like "_p1Range" screams poor triggering practice. Instead of dedicating a _p1Range location to the hero, I would use a general purpose location that's the same size and just center it on the hero when needed (assuming you're using the way I think you are).

None.

>be faceless void >mfw I have no face

Quote from

Kaias

Quote from

Jack

Excellent, that worked. Thanks for your help!

I'm using Notepad++ at the moment, it's nice and minimalist, and quick to load.

I prefer PhpStorm primarily because it has good code hinting and error detection. So when you forget a comma or a parenthesis you know right away and when you want to use the Bring function it tells you exactly what its expecting. Using Notepad++ is indeed a great minimalist environment, however.

By the way, a location name like "_p1Range" screams poor triggering practice. Instead of dedicating a _p1Range location to the hero, I would use a general purpose location that's the same size and just center it on the hero when needed (assuming you're using the way I think you are).

Yeah I was just making a quick map to see how well Oreo works, I wasn't worried about location reuse and such. In a proper map I would be.

Also, http://templesiege.com/test1.php was generated via Oreo Triggers, it works pretty well

might be a few errors in it but I'm happy with how quick it is and how it works. Thanks very much for making this Kaias.

Red classic.

"In short, their absurdities are so extreme that it is painful even to quote them."